Skip to content

feat(aep): add /aep-model object-first design stage (OOUX/ORCA)#13

Merged
memorysaver merged 9 commits into
mainfrom
feat/aep-object-modeling
Jun 16, 2026
Merged

feat(aep): add /aep-model object-first design stage (OOUX/ORCA)#13
memorysaver merged 9 commits into
mainfrom
feat/aep-object-modeling

Conversation

@memorysaver

Copy link
Copy Markdown
Owner

What & why

AEP's design spine is verb-first (Jeff Patton USM): /aep-envision → activity backbone, /aep-map → layered story graph. That plans what the user does but never what the UI looks like structurally/aep-calibrate only locks style (visual-design) and human choice. With no noun-first object model bridging the story map to the UI, build agents invent screen structure per story, which drifts into the disjointed task-wizard UIs that OOUX/OOUI criticize.

This PR adds an automated OOUX/ORCA object-modeling stage between /aep-map and /aep-dispatch. It derives a noun-first Object Map (objects → relationships → CTAs → attributes → screens) from artifacts AEP already produces, takes a short human approval, then governs object structure so the structural UI plan is done before build — leaving only taste (look/voice/journey) to calibration.

Realizes §7 of the research note included in this PR.

Contents

Research (3 commits)docs/research/ooux-object-modeling.md: verb-first vs noun-first analysis, full ORCA process (cited from ooux.com + Medium, cross-checked), the feasibility verdict, and the §7 AEP-integration design.

Implementation (1 commit)

  • New skill skills/product-context/model//aep-model: ORCA draft → human review gate → approved Object Map. Authored references/orca-process.md.
  • New schemas _shared/templates/object-model-schema.yaml (cross-capability ontology, product/object-model.yaml) + object-map-schema.yaml (capability projection, product/maps/<cap>/object-map.yaml).
  • Wiring (additive, gated like calibration): stories[].object_model_refs + object-model dimension in the schema; envision declares the gate for UI-facing products; map auto-drafts after decomposition; dispatch injects the minimal slice and refuses UI stories without an approved map; launch Guardrail 4 aborts likewise; build obeys the injected slice; validate Mode A adds Object Map completeness checks.
  • Docs — glossary terms (Object Model, Object Map, ORCA, CTA, NOM, object-first vs task-oriented), orientation skill table, README.

Design choices

  • Object-first by default, with a per-flow task_oriented escape hatch recorded with a reason (onboarding/checkout/wizard) — per the decision framework in the research note §6.
  • Structural only — object structure + CTA grammar. Visual/voice/journey stay in /aep-calibrate.
  • v2 split-context respected — Object Maps live under product/; product-context.yaml keeps only thin references (per code-review feedback on the research note).
  • Human gate kept — object boundaries/IA are high-impact (same posture as the /aep-map System Map gate); the stage drafts, the human approves.

Verification

  • bash scripts/build-skills.sh --check — generated resources in sync
  • All _shared/model schema YAML parses (python3 -c "import yaml")
  • pre-commit (oxlint/oxfmt) passes
  • No example product-context.yaml ships in this repo, so end-to-end /aep-model dry-run must be exercised in a downstream project.

🤖 Generated with Claude Code

memorysaver and others added 9 commits June 16, 2026 16:16
Capture the verb-first (USM) vs noun-first (OOUX/OOUI) analysis and the
feasibility verdict for auto-generating UI structure across AEP design
stages. ORCA's four rounds map onto inputs AEP already produces, so an
automated Object Map can bridge the story map → UI gap that calibration
(style + human choice only) currently leaves open.

Sourced live this session (defuddle/WebFetch on ooux.com + the Medium
intro) on top of the prior adversarially-verified Task-vs-Object note.
AEP integration (/aep-model skill, design/object-map.yaml) is analysis
only in §7 and deferred to a follow-up.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Keep codex's §7 (v2 split-context artifacts, ux-flow accuracy fix,
draft→review→approved gate) and the docs README Research category. Only
revert the quote paraphrasing: §2/§3/§4 carry the exact ooux.com quotes
again (verified verbatim against this session's defuddle/WebFetch), and
the method line records reproducibility (mgrep --web quota exhausted).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Bridge the verb-first story map to the UI with a noun-first Object Map so
build agents stop inventing one-step-one-screen task-wizard UIs. Realizes
§7 of docs/research/ooux-object-modeling.md.

New:
- skills/product-context/model/ — /aep-model: ORCA draft → human review
  gate → approved Object Map (between /aep-map and /aep-dispatch)
- _shared/templates/object-model-schema.yaml (product/object-model.yaml,
  cross-capability ontology) + object-map-schema.yaml
  (product/maps/<cap>/object-map.yaml, capability ORCA/IA projection)
- model/references/orca-process.md — ORCA derivation + object-first/
  task-oriented decision framework

Wiring (additive, gated like calibration):
- schema: stories[].object_model_refs, object-model quality dimension,
  thin calibration.history reference (artifacts stay under product/)
- envision: declare object-model gate for UI-facing products
- map: auto-draft Object Maps after decomposition; Next Step → /aep-model
- dispatch: inject minimal Object Map slice; refuse UI story w/o approved map
- launch: Guardrail 4 aborts UI story w/o approved Object Map
- build: UI implementation obeys the injected Object Map slice
- validate: Mode A Object Map completeness checks
- docs: glossary terms, orientation skill table, README

Object-first is the default; task-oriented flows are an opt-in escape
hatch recorded with a reason. Structural only — visual/voice/journey stay
in /aep-calibrate.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Three independent gen/eval agents (generator dry-run, evaluator vs repo,
protocol checker) converged on a real producer↔consumer gap plus doc drift.

BLOCKING:
- story→capability was unresolvable (no field; launch grepped a literal
  <capability> placeholder). Add stories[].capability + modules[].kind;
  resolve via story.capability with a coverage-scan fallback; rewrite the
  dispatch slice + launch Guardrail 4 to scan product/maps/*/object-map.yaml
  by covered story id. Define the v1/single-journey default capability
  (project slug).
- pin the canonical screen-id grammar (<object-id>:<view>) so the dispatch
  slice is parseable; define object_model_refs fragment grammar.

IMPORTANT:
- draft ownership: /aep-map drafts, /aep-model refines in place (not
  regenerate); generated_by reflects author.
- stale lifecycle: /aep-map flips an approved map to `stale` on re-decompose;
  dispatch/launch/validate treat stale like draft (abort → /aep-model).
- doc drift: reconcile skill count (19) across orientation + README; add
  /aep-model to dispatch/validate "Where this fits" + README All Skills.
- derivation rubrics (confidence, CTA priority, attribute tiers), frame.yaml/
  v1 fallback, calibrated_from_layer anchor, primary_objects precision,
  map.yaml filename.

build-skills in sync; schema YAML parses.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Bump marketplace.json 2.0.1 → 2.1.0 (minor: additive new skill + capability)
and register the new product-context/model skill in the plugin manifest
(was missing — it would not have installed). Add the matching CHANGELOG entry.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Place the noun-first Object Map step in the detailed Product Context plugin
flow (between the topology merge and /aep-dispatch, alongside /aep-calibrate),
and add a caption to the conceptual Mental Model diagram noting the
specialized control-plane steps it omits (/aep-model, /aep-calibrate,
/aep-validate, /aep-watch). Trim the now-redundant prose note.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@memorysaver memorysaver merged commit 6ce594f into main Jun 16, 2026
1 check passed
@memorysaver memorysaver deleted the feat/aep-object-modeling branch June 16, 2026 09:59
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant